\documentstyle[verbfile,blockpar,desc]{article}
\begin{document}

% Tm version number
\input{version}
% Some logos
\def\tm{\bf tm}
\def\C{\bf C}
\def\pascal{\bf Pascal}

% Width of description column in tabular environments.
\newlength{\descwidth}
\setlength{\descwidth}{0.7\textwidth}
\setcounter{tocdepth}{2}

% A 'listing' environment.
\newenvironment{listing}{\small\begin{flushleft}}{\end{flushleft}}

\title{{\tm} {\pascal} support User Manual \\ {\Large version {\version}}}
\author{C. van Reeuwijk \\ Delft University of Technology}
\maketitle
\section{Introduction}
This manual provides the necessary information to use the {\pascal}
templates of {\tm}.
The information is split in two parts: in section \ref{sec:quickintro}
a quick `cookbook' description of the use of the templates is given.
In the remaining sections a detailed description of the templates is given.
\par
The definitions are described using a {\pascal} type specification,
but without the body.
The following shorthand notations are used:
\par
\begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}p{\descwidth}}
{\tt <type>}
&
A type.
\\
{\tt <cons>}
&
A constructor.
\\
{\tt <elmtype>}
&
A type of an element in a constructor.
\\
{\tt <elmname>}
&
A name of an element in a constructor.
\\
{\tt <something>}
&
The actual contents of this fragment is not important.
\\
{\tt <basename>}
&
Fill in the value of {\tm} variable {\tt basename}.
\end{tabular*}
\section{A quick introduction to the use of the templates}
\label{sec:quickintro}
Before you start to use {\tm} is is useful to realize what the strong and
weak points of {\tm} are:
\begin{itemize}
\item[$+$]
With {\tm} it is simple to exchange structured data between programs
written in different programming languages.
\item[$+$]
Code generated by {\tm} is consistent: any change in the structure
will be reflected in all {\pascal} record definitions and all code
that is generated by {\tm}.
Also,
the generated functions will be consistently correct (or incorrect) for all
types in all generated files.
\item[$-$]
The used representation may not be optimal for your problem.
\end{itemize}
\par
If you are convinced that the advantages outweight the disadvantages
then you can use the following steps to obtain code from {\tm}.
The steps are illustrated by an example.
\begin{enumerate}
\item
Design the structures for your problem,
and encode it in a structure description file.
For the example the following structures are used:
\begin{listing}
\verbfile{plot.ds}
\end{listing}
\item
Create a configuration file that sets the following {\tm} variables:
\begin{itemize}
\item
The variable {\tt basename}:
a general name for the generated code.
\item
The variable {\tt wantdefs}: the names of the definitions that you
will use in your program.
If these definitions require other definitions for types defined in
the datastructure definition file,
this will be deduced, and they will be generated.
For library and support functions this will {\em not} be deduced,
and you must add the names of these functions to {\tt wantdefs}.
\item
The variable {\tt notwantdefs}:
in the rare case that {\tm} deduces that a definition must be generated
while this is not desirable,
this definition can be appended to the list of variable {\tt notwantdefs}.
\end{itemize}
For the running example a file {\tt democonf.t} is used with the
following contents:
\begin{listing}
\verbfile{democonf.t}
\end{listing}
\item
Create a {\tm} skeleton file containing the required {\pascal} environment.
This file should at least contain
\begin{itemize}
\item
An {\tt .insert} of the configuration file, in this example
{\tt democonf.t}.
\item
An {\tt .include} of the necessary template files (see
section \ref{sec:templates}).
\item
An invocation, early in the program, of {\tt Init<basename>}.
\end{itemize}
The file will also contain other stuff,
like definitions for primitive types.
If your {\pascal} does not support separate compilation,
the file must also contain all other code.
You may want to use the {\tm} command {\tt copy} for this code,
so that 
you do not have to check all your {\pascal} code for characters that
{\tm} is sensitive for.
\par
For the example the file is:
\begin{listing}
\verbfile{demo.pt}
\end{listing}
\item
Add a make rule to your makefile to generate the code:
\begin{verbatim}
demo.p : plot.ds demo.pt democonf.t
        tm plot.ds demo.pt > demo.p
\end{verbatim}
\end{enumerate}
\par
The file {\tt demo.p} that is generated from our
example configuration is listed in appendix \ref{sec:demo}.
\section{The {\pascal} templates}
\label{sec:templates}
\subsection{general}
In the design of the {\pascal} templates it has been tried to make
them as general as possible.
However, the original {\pascal} definition is too restricted for
easy code generation,
so that a number of assumptions had to be made.
They are:
\begin{enumerate}
\item
The {\pascal} compiler distinguishes uppercase and lowercase characters
in symbols.
That is,
{\tt ZWOING} is different from {\tt zwoing},
and both are different from {\tt ZwoInG}.
\item
There is no (or a large) upper bound to the number of significant characters
in symbol names.
At least the characters of the type, constructor and element names
and 6 additional characters must be significant.
\item
The following standard functions and procedures are available.
\begin{verbatim}
write( f, e, .. e )
read( f, e )
eof( f )
eoln( f )
new( p, tag )
dispose( p, tag )
\end{verbatim}
\item
The type of the file handles for {\tt read} and {\tt write} is {\tt text}.
\end{enumerate}
\par
In all record types generated by these templates a {\tt next} field is
included that is used to create linked lists of the records.
Therefore, the type of a single element and a list of these elements is the
same.
For clarity
different type names are introduced for single elements and lists.
\par
Due to the strict syntax of {\pascal},
the template must be split up in a number of parts,
one for the {\tt var}, {\tt type} and code sections.
This is also true for the code library.
Therefore,
the following template files are provided:
\begin{flushleft}
\begin{tabular}{|l|l|l|}
\hline
file name & section & purpose \\
\hline
pascode.pt & (code) & Code template. \\
pascode.ht & (code) & {\tt external} declaration template. \\
paslib.pt & (code) & Library of functions. \\
paslib.ht & (code) & {\tt external} declaration of library functions. \\
pastype.pt & {\tt type} & Type declaration template. \\
pasvar.pt & {\tt var} & Variable declaration template. \\
pasgvar.pt & {\tt var} & General variable declarations. \\
\hline
\end{tabular}
\end{flushleft}
\par
The files {\tt pascode.ht} and {\tt paslib.ht} are used for
separate compilation,
see section \ref{sec:sepcomp}.
\subsection{initialization}
Before any other {\tm} generated code is used the procedure
{\tt Init<basename>} must be invoked.
\begin{verbatim}
procedure Init<basename>;
\end{verbatim}
\begin{desc}
Do necessary initializations for generated {\tm} code.
\end{desc}
\subsection{records}
The data is represented using the following {\tt type} definitions:
\begin{verbatim}
<type> = ^Rec<type>;
<type>list = <type>;
\end{verbatim}
\begin{desc}
First, all types and type lists are defined as pointers to a certain
record.
This indirect way is used to prevent problems with mutually recursive
types, since {\pascal} does not mind the introduction of pointers to an
(temporarily) unknown record,
but it {\em does} mind references to unknown types.
For clarity
different type names are introduced for lists and single elements,
even though they are equivalent.
\end{desc}
\begin{verbatim}
Rec<type> = record
    next: <type>list;
    <elmname>: <elmtype>;
    :
    <elmname>: <elmtype>;
end;
\end{verbatim}
\begin{desc}
The representation of tuple types.
The {\tt next} field is used to create linked lists of {\tt <type>} elements.
\end{desc}
\begin{verbatim}
Alltags<type> = ( Tag<cons>, ... Tag<cons> );

Rec<type> = record
    next: <type>list;
    case tag: Alltags<type> of
        Tag<cons> :(
            <elmname>: <elmtype>;
            :
            <elmname>: <elmtype>;
        );
    end
end;
\end{verbatim}
\begin{desc}
The representation of constructor types.
The {\tt next} field is used to create linked lists of {\tt <type>} elements.
The possible constructors for the type are recognized by the contents of
the {\tt tag} field,
which contains a value of the enumerated type {\tt Alltags<type>}.
For each constructor of a variant is defined.
\end{desc}
\subsection{allocation and freeing}
These procedures handle allocation and freeing of instances of the constructors.
\begin{verbatim}
procedure New<cons>(
    e1:<elmtype>;
    :
    en:<elmtype>;
    var n:<type>
);
procedure New<type>(
    e1:<elmtype>;
    :
    en:<elmtype>;
    var n:<type>
);
\end{verbatim}
\begin{desc}
Allocate space for a new of a constructor or tuple record,
and set each of the elements to the value of the given parameter
for that element.
Set the first parameter ({\tt n}) to the new record.
The {\tt next} field is set to {\tt nil}.
For constructors the {\tt tag} field is set to {\tt Tag<cons>}.
To request the generation of all {\tt New<cons>} functions for a certain
constructor type,
{\tt New<type>} must be added to {\tt wantdefs},
see section \ref{sec:config} for an explanation of the use of {\tt wantdefs}.
\end{desc}
\begin{verbatim}
procedure Free<type>( var e: <type> );
procedure Free<type>list( var e: <type>list );
\end{verbatim}
\begin{desc}
Free an instance of {\tt <type>} or {\tt <type>list}.
The parameter {\tt e} will be set to {\tt nil}.
\end{desc}
\begin{verbatim}
procedure Rfre<type>( var e: <type> );
procedure Rfre<type>list( var e: <type>list );
\end{verbatim}
\begin{desc}
Recursively free an instance of {\tt <type>} or {\tt <type>list}
and all elements in it.
The parameter {\tt e} will be set to {\tt nil}.
\end{desc}
\begin{verbatim}
procedure Stat<basename>( var f: text );
\end{verbatim}
\begin{desc}
Write statistics of allocation and freeing to file {\tt f}.
Note that the code to collect statistics is only generated when the
generation of {\tt Stat<basename>} has been requested.
\end{desc}
\subsection{appending and concatenation}
These functions handle appending (adding single elements at the end of the list)
and concatenation (adding a list at the end of an other list).
Since all single elements have their {\tt next} field set to {\tt nil}
by the {\tt New<cons>} or {\tt New<type>} function,
both classes of functions actually use the same code.
\begin{verbatim}
function App<type>( var l: <type>list; e: <type> ): <type>;
\end{verbatim}
\begin{desc}
Append element {\tt e} after list {\tt l},
and return the new list.
Remaining copies to the parameters {\tt l} and {\tt e} are still valid,
but only the complete constructed list should be freed.
The function behaves correctly if {\tt l} or {\tt e} is {\tt nil}.
\end{desc}
\subsection{recursive copying}
These functions handle recursive copying of instances of types
and lists of types.
Copying means that new instances are allocated for types that must
be allocated.
\begin{verbatim}
function Copy<type>( <type> e ): <type>;
function Copy<type>list( <type>list e ): <type>list;
\end{verbatim}
\begin{desc}
Recursively copy instance {\tt e} of type {\tt <type>} or
{\tt <type>list}.
\end{desc}
\subsection{input and output}
These functions handle reading and writing of a textual description of the
datastructures.
They assume the existence of the following functions:
\begin{flushleft}
\begin{tabular}{|l|l|}
\hline
name & purpose \\
\hline
{\tt tmgetc} &  Read next char of a text file. \\
{\tt tmreadspc} & Skip spaces and comment. \\
{\tt tmneedc} & Expect given char in file. \\
{\tt tmreadobrac} & Count open brackets. \\
{\tt tmreadcbrac} & Balance open brackets. \\
\hline
\end{tabular}
\end{flushleft}
See section \ref{sec:lib} for a detailed description.
\par
The {\tt Read<type>}, {\tt Read<type>list} and supporting routines
assume the existence of a few variables:
\begin{flushleft}
\begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}p{\descwidth}}
{\tt tmcurchar}
&
This variable must contain the first character to use for all read
functions.
All read functions can assume that it is filled on entry,
and must ensure that it is filled on exit.
\par
This implies that before the top level {\tt Read<type>} function is used,
the variable must be filled with a call to {\tt tmgetc}
(see section \ref{sec:lib}).
\\
{\tt tmeolnchar}
&
Special char for the eoln condition as used in {\pascal}.
\\
{\tt tmeofchar}
&
Special char for the eof condition as used in {\pascal}.
\end{tabular*}
\end{flushleft}
\par
The variables {\tt tmeolnchar} and {\tt tmeofchar} are
set to their value in the procedure {\tt Init<basename>}.
\begin{verbatim}
function Read<type>( var f, rf: text; var p: <type> );
function Read<type>list( var f, rf: text; var p: <type>list );
\end{verbatim}
\begin{desc}
Read an instance of record {\tt <type>} or {\tt <type>list} from
file {\tt f},
allocate memory to hold the data that is read,
and set {\tt p} to the new data.
If no error occurs, a value {\tt false} is returned.
If an error occurs during reading,
a value {\tt true} is returned, and an error message is written
to the file {\tt rf}.
For all the data that has been read before the error memory is allocated,
but the allocated records may contain garbage values for the record
elements that could not be read due to the error.
\end{desc}
\begin{verbatim}
procedure Write<type>( var f: text; t: <type> );
procedure Write<type>list( var f: text, t: <type>list );
\end{verbatim}
\begin{desc}
Write an instance of record {\tt <type>} or {\tt <type>list}
to file {\tt f} in the internal representation of {\tm}.
\end{desc}
\subsection{comparison}
These functions handle recursive comparison of structures.
Given two datastructures {\tt a} and {\tt b},
an integer ${\tt n}<0$ is returned if ${\tt a}<{\tt b}$,
0 if ${\tt a}={\tt b}$,
and an integer ${\tt n}>0$ if ${\tt a}>{\tt b}$,
\par
For comparison the following rules are applied:
\begin{itemize}
\item
Tuples are equal if all their elements are equal,
else the first differing element from the left determines the comparison.
\item
Constructors are ordered according to their order of definition in the
datastructure file,
where the first constructor is the smallest.
Constructors are equal if all their elements are equal,
else the first differing element from the left determines the comparison.
\item
Lists are equal if all their elements are equal,
else the first differing element from the left determines the comparison,
or else the shortest list is the smallest.
\end{itemize}
\par
These functions are mainly intended for equality comparison,
and to impose `some' repeatable ordering on the datastructures.
The ordering may be different from the desired ordering.
If an other comparison function is required for one datatype,
the generation of the standard function can be suppressed by
using {\tt notwantdefs}, see section \ref{sec:config}.
\begin{verbatim}
function Cmp<type>( a: <type>; b: <type> ): integer;
function Cmp<type>list( a: <type>list; b: <type>list ): integer;
\end{verbatim}
\begin{desc}
Compare datastructures {\tt a} and {\tt b}, and return a code
according to the table listed previously.
\end{desc}
\section{Pascal code library}
\label{sec:lib}
The {\pascal} code library provides definitions in
the same class as the generated definitions for a number of commonly used
primitive types.
It also contains low-level definitions that are required by the generated
definitions.
\begin{verbatim}
procedure tmgetc( var f: text );
\end{verbatim}
\begin{desc}
Read a character from file {\tt f} in the global variable {\tt tmcurchar}.
The eoln condition is converted to a special
{\tt tmeolnchar} character.
During eof {\tt tmeofchar} is put into {\tt tmcurchar}.
\end{desc}
\begin{verbatim}
procedure tmreadspc( var f: text );
\end{verbatim}
\begin{desc}
Skip all spaces, tabs, form feeds and comment in the input up to the
next non-white character.
A comment is started with a {\em single} {\tt |} and is terminated by a newline.
To remain compatible with the Miranda parser,
a file should always use {\tt ||} as comment start,
but to check this causes problems in parsing.
\end{desc}
\begin{verbatim}
function tmneedc( var f, rf: text; c: char ): boolean;
\end{verbatim}
\begin{desc}
After skipping spaces, tabs, form feeds and comment,
try to read character {\tt c} from file {\tt f}.
Return a value {\tt true} and write an error message to {\tt rf} if this
is not possible,
else return {\tt false}.
\end{desc}
\begin{verbatim}
function tmreadc( var f, rf: text; var c: char ): boolean;
\end{verbatim}
\begin{desc}
Read a char from file {\tt f} into {\tt c}.
Preceding blanks and comment are {\em not} skipped.
Backslash escape sequences are recognized.
This function is used by {\tt Readchar},
and should be used by {\tt Readstring} if it is implemented.
\end{desc}
\begin{verbatim}
procedure tmreadobrac( var f: text; var n: integer );
function tmreadcbrac( var f, rf: text; n: integer ): boolean;
\end{verbatim}
\begin{desc}
Handle brackets around constructors.
{\tt tmreadobrac()} counts and sets parameter {\tt n} to the number
of open brackets (`{\tt (}') it encounters up to the first character
that is not white space, comment  or an open bracket.
{\tt tmreadcbrac()} tries to read {\tt n} close brackets (`{\tt )}'),
and will return {\tt true} and write an error message to {\tt rf} if this
is not possible,
or will return {\tt false} if it is successful.
\end{desc}
\begin{verbatim}
procedure tmwritec( var f: text; c: char );
\end{verbatim}
\begin{desc}
Write a char {\tt c} to file {\tt f}.
Backslash escape sequences are used when necessary.
This function is used by {\tt Writechar},
and should be used by {\tt Writestring} if it is implemented.
\end{desc}
\begin{verbatim}
function Readreal( var f, rf: text; var r: real ): boolean;
procedure Writereal( var f: text; r: real );
procedure Rfrereal( r: real );
function Cmpreal( a, b: real ): integer;
\end{verbatim}
\begin{desc}
Module functions for type `real'.
\end{desc}
\begin{verbatim}
int Readinteger( var f, rf: text; var i: integer ): boolean;
procedure Writeinteger( var f: text; i: integer );
procedure Rfreinteger( r: integer );
function Cmpinteger( a, b: integer ): integer;
\end{verbatim}
\begin{desc}
Module functions for type `integer'.
\end{desc}
\begin{verbatim}
function Readboolean( var f, rf: text; var b: boolean ): boolean;
procedure Writeboolean( var f: text; b: boolean );
procedure Rfreboolean( b: boolean );
function Cmpboolean( a, b: boolean ): integer;
\end{verbatim}
\begin{desc}
Module functions for type `boolean'.
\end{desc}
\begin{verbatim}
function Readchar( var f, rf: text; var c: char ): boolean;
procedure Writechar( var f: text; c: char );
procedure Rfrechar( c: char );
function Cmpchar( a, b: char ): integer;
\end{verbatim}
\begin{desc}
Module functions for type `char'.
\end{desc}
\section{{\tm} configuration variables}
\label{sec:config}
The templates use a few {\tm} variables to modify the contents
of the generated code.
Unless stated otherwise,
it is not necessary to set them;
a reasonable default will be chosen.
\par
\begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}p{\descwidth}}
{\tt basename}
&
This variable is used to generate the names of 
definitions that are generated only once
(e.g. initialization and statistics procedures).
This variable
{\em must}
be set.
\\
{\tt wantdefs}
&
If set,
this variable contains the names of the type and function definitions that
must be generated.
If these functions require the definition of other functions,
the necessary functions will be generated,
but will be declared {\tt static}.
If {\tt alldefs} is set all possible definitions are generated.
\par
There is one exception:
to request the generation of {\tt New<cons>} functions for a certain
constructor type {\tt <type>},
{\tt New<type>} must be added to {\tt wantdefs}.
\\
{\tt notwantdefs}
&
If set,
this variable contains the names of the type and function definitions for
which under all conditions {\tt no} code must be generated.
\\
{\tt alldefs}
&
If set,
this variable indicates that all possible type and function definitions must
be generated.
\end{tabular*}
\par
At least one of the variables {\tt wantdefs} and {\tt alldefs} must be set.
\par
The the variable {\tt wantdefs} should contain the names of all definitions
that must be generated.
These definitions may require other definitions,
and for for the types defined in the datastructure file
these requirements will be deduced,
and the necessary code will be generated.
However,
the need for support functions (e.g. {\tt tmgetc}) and functions for standard
primitive types (e.g. {\tt Readreal}) is {\em not} deduced,
and the generation of these functions must be requested explicitly.
\section{Separate compilation}
\label{sec:sepcomp}
For {\pascal} compilers that support separate compilation some special
template files are available: {\tt pascode.ht} and {\tt paslib.ht}.
These files contain {\tt external} declarations for the code in {\tt pascode.pt}
and {\tt paslib.pt} respectively.
Only for the definitions that have been requested using {\tt wantdefs}
declarations will be generated.
For example, an external declaration for {\tt tmgetc} will look like:
\begin{verbatim}
procedure tmgetc( var f: text ); external;
\end{verbatim}
Inclusion of these declarations in other parts of the program must be
arranged by the the programmer.
The variables generated by {\tt pasvar.pt} are only necessary
for the code generated by {\tt pascode.pt},
so that they do not have to be made visible to other files.
Provided that all {\tt Read<type>} functions for primitive
types are in the same file as the generated code,
the variables of {\tt pasgvar.pt} do not have to be make visible either.
\appendix
\pagebreak
\section{Listing of the file {\tt demo.p}}
\label{sec:demo}
\begin{listing}
\verbfile{demo.p}
\end{listing}
\end{document}
